{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Grover's Algorithm and Amplitude Amplification\n",
    "\n",
    "Grover's algorithm is one of the most famous quantum algorithms introduced by Lov Grover in 1996 \\[1\\]. It has initially been proposed for unstructured search problems, i.e. for finding a marked element in a unstructured database. However, Grover's algorithm is now a subroutine to several other algorithms, such as Grover Adaptive Search \\[2\\]. For the details of Grover's algorithm, please see [Grover's Algorithm](https://learn.qiskit.org/course/ch-algorithms/grovers-algorithm) in the Qiskit textbook.\n",
    "\n",
    "Qiskit implements Grover's algorithm in the `Grover` class. This class also includes the generalized version, Amplitude Amplification \\[3\\], and allows setting individual iterations and other meta-settings to Grover's algorithm.\n",
    "\n",
    "**References:**\n",
    "\n",
    "\\[1\\]: L. K. Grover, A fast quantum mechanical algorithm for database search. Proceedings 28th Annual Symposium on\n",
    "the Theory of Computing (STOC) 1996, pp. 212-219. https://arxiv.org/abs/quant-ph/9605043\n",
    "\n",
    "\\[2\\]: A. Gilliam, S. Woerner, C. Gonciulea, Grover Adaptive Search for Constrained Polynomial Binary Optimization.\n",
    "https://arxiv.org/abs/1912.04088\n",
    "\n",
    "\n",
    "\\[3\\]: Brassard, G., Hoyer, P., Mosca, M., & Tapp, A. (2000). Quantum Amplitude Amplification and Estimation. http://arxiv.org/abs/quant-ph/0005055"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Grover's algorithm\n",
    "\n",
    "Grover's algorithm uses the Grover operator $\\mathcal{Q}$ to amplify the amplitudes of the good states:\n",
    "\n",
    "$$\n",
    "    \\mathcal{Q} = \\mathcal{A}\\mathcal{S_0}\\mathcal{A}^\\dagger \\mathcal{S_f}\n",
    "$$\n",
    "\n",
    "Here, \n",
    "* $\\mathcal{A}$ is the initial search state for the algorithm, which is just Hadamards, $H^{\\otimes n}$ for the textbook Grover search, but can be more elaborate for Amplitude Amplification\n",
    "* $\\mathcal{S_0}$ is the reflection about the all 0 state\n",
    "$$\n",
    "    |x\\rangle \\mapsto \\begin{cases} -|x\\rangle, &x \\neq 0 \\\\ |x\\rangle, &x = 0\\end{cases}\n",
    "$$\n",
    "* $\\mathcal{S_f}$ is the oracle that applies \n",
    "$$\n",
    "    |x\\rangle \\mapsto (-1)^{f(x)}|x\\rangle\n",
    "$$ \n",
    "&nbsp;&nbsp;&nbsp;&nbsp;　where $f(x)$ is 1 if $x$ is a good state and otherwise 0.\n",
    "\n",
    "In a nutshell, Grover's algorithm applies different powers of $\\mathcal{Q}$ and after each execution checks whether a good solution has been found. \n",
    "\n",
    "\n",
    "### Running Grover's algorithm \n",
    "\n",
    "To run Grover's algorithm with the `Grover` class, firstly, we need to specify an oracle for the circuit of Grover's algorithm. In the following example, we use `QuantumCircuit` as the oracle of Grover's algorithm. However, there are several other class that we can use as the oracle of Grover's algorithm. We talk about them later in this tutorial.\n",
    "\n",
    "Note that the oracle for `Grover` must be a _phase-flip_ oracle. That is, it multiplies the amplitudes of the of \"good states\" by a factor of $-1$. We explain later how to convert a _bit-flip_ oracle to a phase-flip oracle. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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",
      "text/plain": [
       "<Figure size 843.845x200.667 with 1 Axes>"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from qiskit import QuantumCircuit\n",
    "from qiskit.algorithms import AmplificationProblem\n",
    "\n",
    "# the state we desire to find is '11'\n",
    "good_state = ['11']\n",
    "\n",
    "# specify the oracle that marks the state '11' as a good solution\n",
    "oracle = QuantumCircuit(2)\n",
    "oracle.cz(0, 1)\n",
    "\n",
    "# define Grover's algorithm\n",
    "problem = AmplificationProblem(oracle, is_good_state=good_state)\n",
    "\n",
    "# now we can have a look at the Grover operator that is used in running the algorithm\n",
    "# (Algorithm circuits are wrapped in a gate to appear in composition as a block\n",
    "# so we have to decompose() the op to see it expanded into its component gates.)\n",
    "problem.grover_operator.decompose().draw(output='mpl')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Then, we specify a backend and call the `run` method of `Grover` with a backend to execute the circuits. The returned result type is a `GroverResult`. \n",
    "\n",
    "If the search was successful, the `oracle_evaluation` attribute of the result will be `True`. In this case, the most sampled measurement, `top_measurement`, is one of the \"good states\". Otherwise, `oracle_evaluation` will be False.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Result type: <class 'qiskit.algorithms.amplitude_amplifiers.grover.GroverResult'>\n",
      "\n",
      "Success!\n",
      "Top measurement: 11\n"
     ]
    }
   ],
   "source": [
    "from qiskit.algorithms import Grover\n",
    "from qiskit.primitives import Sampler\n",
    "\n",
    "\n",
    "grover = Grover(sampler=Sampler())\n",
    "result = grover.amplify(problem)\n",
    "print('Result type:', type(result))\n",
    "print()\n",
    "print('Success!' if result.oracle_evaluation else 'Failure!')\n",
    "print('Top measurement:', result.top_measurement)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the example, the result of `top_measurement` is `11` which is one of \"good state\". Thus, we succeeded to find the answer by using `Grover`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Using the different types of classes as the oracle of `Grover`\n",
    "In the above example, we used `QuantumCircuit` as the oracle of `Grover`. \n",
    "However, we can also use `qiskit.quantum_info.Statevector` as oracle.\n",
    "All the following examples are when $|11\\rangle$ is \"good state\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Result type: <class 'qiskit.algorithms.amplitude_amplifiers.grover.GroverResult'>\n",
      "\n",
      "Success!\n",
      "Top measurement: 11\n"
     ]
    }
   ],
   "source": [
    "from qiskit.quantum_info import Statevector\n",
    "oracle = Statevector.from_label('11')\n",
    "problem = AmplificationProblem(oracle, is_good_state=['11'])\n",
    "\n",
    "grover = Grover(sampler=Sampler())\n",
    "result = grover.amplify(problem)\n",
    "print('Result type:', type(result))\n",
    "print()\n",
    "print('Success!' if result.oracle_evaluation else 'Failure!')\n",
    "print('Top measurement:', result.top_measurement)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Internally, the statevector is mapped to a quantum circuit:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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",
      "text/plain": [
       "<Figure size 287.294x200.667 with 1 Axes>"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "problem.grover_operator.oracle.decompose().draw(output='mpl')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Qiskit allows for an easy construction of more complex oracles:\n",
    "* `PhaseOracle`: for parsing logical expressions such as `'~a | b'`. This is especially useful for solving 3-SAT problems and is shown in the accompanying [Grover Examples](07_grover_examples.ipynb) tutorial.\n",
    "\n",
    "Here we'll use the `PhaseOracle` for the simple example of finding the state $|11\\rangle$, which corresponds to `'a & b'`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "tags": []
   },
   "outputs": [
    {
     "data": {
      "image/png": "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",
      "text/plain": [
       "<Figure size 370.906x200.667 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "from qiskit.circuit.library.phase_oracle import PhaseOracle\n",
    "from qiskit.exceptions import MissingOptionalLibraryError\n",
    "\n",
    "# `Oracle` (`PhaseOracle`) as the `oracle` argument\n",
    "expression = '(a & b)'\n",
    "try:\n",
    "    oracle = PhaseOracle(expression)\n",
    "    problem = AmplificationProblem(oracle)\n",
    "    display(problem.grover_operator.oracle.decompose().draw(output='mpl'))\n",
    "except MissingOptionalLibraryError as ex:\n",
    "    print(ex)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "tags": []
   },
   "source": [
    "Which we observe that this oracle implements a phase flip when the state is  $|11\\rangle$\n",
    "\n",
    "As mentioned above, Grover's algorithm requires a _phase-flip_ oracle. A bit-flip oracle flips the state of an auxiliary qubit if the other qubits satisfy the condition. To use these types of oracles with Grover's we need to convert the bit-flip oracle to a phase-flip oracle by sandwiching the auxiliary qubit of the bit-flip oracle by $X$ and $H$ gates.\n",
    "\n",
    "**Note:** This transformation from a bit-flip to a phase-flip oracle holds generally and you can use this to convert your oracle to the right representation."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Amplitude amplification\n",
    "Grover's algorithm uses Hadamard gates to create the uniform superposition of all the states at the beginning of the Grover operator $\\mathcal{Q}$. If some information on the good states is available, it might be useful to not start in a uniform superposition but only initialize specific states. This, generalized, version of Grover's algorithm is referred to _Amplitude Amplification_.\n",
    "\n",
    "In Qiskit, the initial superposition state can easily be adjusted by setting the `state_preparation` argument.\n",
    "\n",
    "### State preparation\n",
    "\n",
    "A `state_preparation` argument is used to specify a quantum circuit that prepares a quantum state for the start point of the amplitude amplification.\n",
    "By default, a circuit with $H^{\\otimes n}$ is used to prepare uniform superposition (so it will be Grover's search). The diffusion circuit of the amplitude amplification reflects `state_preparation` automatically."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "tags": []
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "state preparation circuit:\n"
     ]
    },
    {
     "data": {
      "image/png": "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",
      "text/plain": [
       "<Figure size 371.107x284.278 with 1 Axes>"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "import numpy as np\n",
    "\n",
    "# Specifying `state_preparation` \n",
    "# to prepare a superposition of |01>, |10>, and |11>\n",
    "oracle = QuantumCircuit(3)\n",
    "oracle.ccz(0, 1, 2)\n",
    "\n",
    "theta = 2 * np.arccos(1 / np.sqrt(3))\n",
    "state_preparation = QuantumCircuit(3)\n",
    "state_preparation.ry(theta, 0)\n",
    "state_preparation.ch(0,1)\n",
    "state_preparation.x(1)\n",
    "state_preparation.h(2)\n",
    "\n",
    "# we only care about the first two bits being in state 1, thus add both possibilities for the last qubit\n",
    "problem = AmplificationProblem(oracle, state_preparation=state_preparation, is_good_state=['110', '111'])\n",
    "\n",
    "# state_preparation\n",
    "print('state preparation circuit:')\n",
    "problem.grover_operator.state_preparation.draw(output='mpl')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Success!\n",
      "Top measurement: 111\n"
     ]
    }
   ],
   "source": [
    "grover = Grover(sampler=Sampler())\n",
    "result = grover.amplify(problem)\n",
    "print('Success!' if result.oracle_evaluation else 'Failure!')\n",
    "print('Top measurement:', result.top_measurement)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Full flexibility\n",
    "\n",
    "For more advanced use, it is also possible to specify the entire Grover operator by setting the `grover_operator` argument. This might be useful if you know more efficient implementation for $\\mathcal{Q}$ than the default construction via zero reflection, oracle and state preparation.\n",
    "\n",
    "The `qiskit.circuit.library.GroverOperator` can be a good starting point and offers more options for an automated construction of the Grover operator. You can for instance \n",
    "* set the `mcx_mode` \n",
    "* ignore qubits in the zero reflection by setting `reflection_qubits`\n",
    "* explicitly exchange the $\\mathcal{S_f}, \\mathcal{S_0}$ and $\\mathcal{A}$ operations using the `oracle`, `zero_reflection` and `state_preparation` arguments"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For instance, imagine the good state is a three qubit state $|111\\rangle$ but we used 2 additional qubits as auxiliary qubits. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "tags": []
   },
   "outputs": [
    {
     "data": {
      "image/png": "iVBORw0KGgoAAAANSUhEUgAAALAAAAFvCAYAAADqqEEQAAAAOXRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjYuMiwgaHR0cHM6Ly9tYXRwbG90bGliLm9yZy8o6BhiAAAACXBIWXMAAA9hAAAPYQGoP6dpAAAWvUlEQVR4nO3af1DU973v8ecqSZBfUcDc9Qghi4gVgmAlHMnkJsHB03BsbXubnxKTzrV3nE7o0I4jtslNbc8fZcg406nS06uZaTv943Jok965RpO5vTN0bqm3SSUWS5Vog8JlgW2yAVS2eBrY7/2DlhPCgrLusuf95fWYcTLu5/PZvMWnX767i8dxHAcRo5YlegCRW6GAxTQFLKYpYDFNAYtpClhMU8BimgIW0xSwmKaAxTQFLKYpYDFNAYtpClhMU8BimgIW0xSwmKaAxTQFLKYpYDFNAYtpClhMU8BimgIW0xSwmKaAxTQFLKYpYDFNAYtpClhMU8BimgIW0xSwmKaAxTQFLKYpYDFNAYtpClhMU8BimgIW0xSwmKaAxTQFLKYpYDFNAYtpClhMU8BimgIW0xSwmKaAxTQFLKYpYDFtSQQcDAZpaGigoKCA5ORkcnNzqa+vJxQKsWfPHjweD83NzYkeM65CH4C/E3p/O/Xf0AeJnig2khI9QLx1dnZSU1NDIBAgNTWVoqIiBgcHOXz4MD09PQwPDwNQVlaW2EHjJNgDfR0w0j97bVUu5JVD9rrFnytWPI7jOIkeIl6CwSCbN2/G7/ezb98+Dh48SHp6OgAvvfQSBw4cICkpicnJSUZHR8nIyEjwxLF1+S3oab/xvnX/EXx/H/954sHVAe/atYuWlhbq6uo4cuTIrPWysjLOnj2Lz+fj0qVLCZgwfgZ+D92/uPn9G/8B1m6K3zzx4tp74O7ublpbW8nOzqaxsTHini1btgBQWlo64/HLly+zc+dO0tPTWbVqFc888wwffGDnpnFyAt69iSvvR73bPnXOGtcG3NLSQjgcpra2lrS0tIh7VqxYAcwM+Nq1a1RVVeH3+2lpaeHYsWO0t7fz6U9/mnA4vCiz36r3LsCH4ws78+E4vHcxPvPEk2tfxLW1tQFQVVU15x6/3w/MDPjYsWMMDAzwq1/9irvvvhuAnJwc7r//fo4fP87nPve5+A0dI4F3ojzXDWuKYjtLvLk24L6+PgDy8vIirk9MTHDq1ClgZsAnTpzggQcemI4XoLKykvz8fF577bWoAi4vLycQCCz4XLQOPnUS338ovfHGj+l48yyfqd8Rh4luzOv10tHRseBzrg04FAoBMD4e+Xtpa2srwWCQ9PR0fD7f9OPnz5/nsccem7W/uLiY8+fPRzVLIBBgYGAgqrPRuH59gfcPfzV+/c+LOmcsuDZgr9fLyMgIZ86cobKycsba0NAQ+/fvB2DTpk14PJ7ptZGREVauXDnr+TIzM7lw4ULUsyymkT9HF+FIaIC1a9fGeJqbE+3XyLUBV1dX093dTVNTE9u3b6ewsBCA06dPs3v3boLBILA4H2BE863xVoz44e1/Wfi5+n96lIM/fDT2A8WRa9+FaGhoICsri/7+foqLiykpKWH9+vVUVFSQn5/Ptm3bgNlvoa1atYrR0dFZzzc8PExmZuZijH7LVq6FtOyFnUnLhjsTc/G9Ja4NOCcnh/b2dnbs2EFycjK9vb1kZmZy9OhRTp48ycWLU+8ZfTzgjRs3RrzXPX/+PBs3blyU2W+VxwNFNbD8tpvbv/w2KP7HqXPWuPqTuLmMjY2RkZGBx+Ph2rVrpKSkTK8dOnSI559/nkuXLpGTkwPAW2+9xdatW/n5z3/O5z//+USNvWBXBqHzf8z/nvBtK6Ds83Dn3y3eXLG0JAP+W5AbNmzgnXdmvml69epVSkpKyM7O5tvf/jbXr1+noaGB1atX85vf/IZly2x90/pwHAbPwcBZ+PPIzLX1D8PfFU9FbJWtv40Y6erqAmbfPgBkZGTQ1tbGmjVrePLJJ/nSl77E/fffz4kTJ8zFC1Nx5pVD5X+GB/bOXMsrtx0vuPhdiPnMFzDAunXrOHHixGKOFHceDySnAx7A+et/XcDeJSUGbhSw2LEkr8B/+zkJsW9JXoHFPRSwmKaAxTQFLKYpYDFNAYtpClhMU8BimgIW0xSwmKaAxTQFLKYpYDFNAYtpClhMU8BimgIW0xSwmKaAxTQFLKYpYDFNAYtpClhMU8BimgIW0xSwmKaAxTQFLKYpYDFNAYtpClhMU8BimgIW0xSwmKaAxTQFLKYpYDFNAYtpClhMU8BimgIW0xSwmKaAxTQFLKYpYDFtSQQcDAZpaGigoKCA5ORkcnNzqa+vJxQKsWfPHjweD83NzYkeM+7CE4CT6CliKynRA8RbZ2cnNTU1BAIBUlNTKSoqYnBwkMOHD9PT08Pw8DAAZWVliR00TiYn4L0L4O+EK0MfWXBg6BzctQGWG67A4ziOy/5N/ptgMMjmzZvx+/3s27ePgwcPkp6eDsBLL73EgQMHSEpKYnJyktHRUTIyMhI8cWyNBaHz53D96tx7kjOg7D9BWvbizRVLrg54165dtLS0UFdXx5EjR2atl5WVcfbsWXw+H5cuXUrAhPETGoaO/w4fXr/x3tuSoXwXpGbGf65Yc+09cHd3N62trWRnZ9PY2Bhxz5YtWwAoLS2dfszv91NXV0dFRQV33HEHHo9nUeaNtXOv31y8MLXv3OvxnSdeXBtwS0sL4XCY2tpa0tLSIu5ZsWIFMDPgd999l1dffRWv18t99923KLPG2pUhuBpY2JmrgY/dIxvh2oDb2toAqKqqmnOP3+8HZgb84IMPMjQ0xPHjx6muro7vkHEy8PvFPZdIhl9/zq+vrw+AvLy8iOsTExOcOnUKmBnwsmWx/zddXl5OILDAS+It+K9P/E8K1mxZ8Ln/8786+Ic9n4v9QDfB6/XS0dGx4HOuDTgUCgEwPj4ecb21tZVgMEh6ejo+ny+uswQCAQYGBuL6//goZzK6+3Yn7FnUOWPBtQF7vV5GRkY4c+YMlZWVM9aGhobYv38/AJs2bYr7CzWv1xvX5/+4f528FvW5tWvXxniamxPt18i1AVdXV9Pd3U1TUxPbt2+nsLAQgNOnT7N7926CwSCwOB9gRPOt8Vb4z8I7/3vh5x7/Lw/ztSP+2A8UR659EdfQ0EBWVhb9/f0UFxdTUlLC+vXrqaioID8/n23btgEz73/dYs1GWH77ws4k3QHeT8RnnnhybcA5OTm0t7ezY8cOkpOT6e3tJTMzk6NHj3Ly5EkuXrwIuDPg5bdDfuWN932Ub+vCo//3wLW3EAAbN27kxIkTsx4fGxujt7eXZcuWce+99yZgsvi7uxz+NQT/7ybuXu4un/plkasDnsu5c+dwHIfCwkJSUlJmrb/yyisAnD9/fsbv77nnHsrLbfxNezxQ+DCkr4be0xAKzt6Tlg1598Ga4kUfL2aWZMBdXV3A3LcPjz32WMTfP/vss/z4xz+O62yxtqYYvEVwZQCG++HSqX9b+/tnp0K3TAFH4Lafb/J4YGXO1K9L/5epnwn22I8XXPwibj43CljsWJJX4L/9nITYtySvwOIeClhMU8BimgIW0xSwmKaAxTQFLKYpYDFNAYtpClhMU8BimgIW0xSwmKaAxTQFLKYpYDFNAYtpClhMU8BimgIW0xSwmKaAxTQFLKYpYDFNAYtpClhMU8BimgIW0xSwmKaAxTQFLKYpYDFNAYtpClhMU8BimgIW0xSwmKaAxTQFLKYpYDFNAYtpClhMU8BimgIW0xSwmKaAxbQlEXAwGKShoYGCggKSk5PJzc2lvr6eUCjEnj178Hg8NDc3J3rMuJn4C/jPQtcJwPnrg87U49YlJXqAeOvs7KSmpoZAIEBqaipFRUUMDg5y+PBhenp6GB4eBqCsrCyxg8ZBOAyXfg39nTAZIdb2/wa5ZZD/ACwzeinzOI7j3HibTcFgkM2bN+P3+9m3bx8HDx4kPT0dgJdeeokDBw6QlJTE5OQko6OjZGRkJHji2AlPwu+PQ7Dnxnuz18GmnbBsefznijVXB7xr1y5aWlqoq6vjyJEjs9bLyso4e/YsPp+PS5cuJWDC+LnQBv1nbn5/7idhw7b4zRMvRr9x3Fh3dzetra1kZ2fT2NgYcc+WLVsAKC0tnX7slVde4Qtf+AJ5eXmkpKTwiU98ghdeeIGxsbFFmTsW/vLnqXvehRg4O3XOGtcG3NLSQjgcpra2lrS0tIh7VqxYAcwM+NChQyxfvpzvfOc7vPHGG3z5y1/mBz/4AY888gjhcHhRZr9Vg13gTC7sTHgSBv8Qn3niybUv4tra2gCoqqqac4/f7wdmBvzaa6+xevXq6d8/9NBDrF69mtraWn7961/z4IMPxmni2PmgN8pzl+GeipiOEneuDbivrw+AvLy8iOsTExOcOnUKmBnwR+P9m/LycgAGBgaimqW8vJxAIBDV2Wh8a9cb3HNXyYLP/e7tLj67ryYOE92Y1+ulo6NjwedcG3AoFAJgfHw84nprayvBYJD09HR8Pt+8z/XLX/4SgI0bN0Y1SyAQiDr+aIyFrkR17trY6KLOGQuuDdjr9TIyMsKZM2eorKycsTY0NMT+/fsB2LRpEx6PZ87nGRgY4MUXX+SRRx6J+r1ir9cb1blo+UfOc6/vgQWfGxg5z9q1a+Mw0Y1F+zVybcDV1dV0d3fT1NTE9u3bKSwsBOD06dPs3r2bYDAIzP8BxtjYGJ/97Ge5/fbb+eEPfxj1LNF8a7wVoWH4TRTj/tM/7+XQqr2xHyiOXPsuRENDA1lZWfT391NcXExJSQnr16+noqKC/Px8tm2betPzo/e/HzU+Ps5nPvMZLl++zC9+8QvWrFmzmOPfktRMyM5f2JnsfEhZFZ954sm1Aefk5NDe3s6OHTtITk6mt7eXzMxMjh49ysmTJ7l48SIQOeAPP/yQRx99lI6ODt544w2KiooWe/xbVvTIzQeZsmpqv0Wu/iRuLmNjY2RkZODxeLh27RopKSnTa+FwmCeffJLjx4/z+uuvT1+pLfpLaOoHeEb6596zKhdKPg23py7eXLHk2nvg+Zw7dw7HcSgsLJwRL8Bzzz3Hz372M77+9a+TkpLCm2++Ob22bt26iG+z/Xt1eypseQKuDE19MjfaP/UTaEm3w8pcyCmFO+3cGUXmLEEvv/yyAziPP/74rLW8vDyHqR86nPXrRz/60eIPK/Naklfgrq4uIPL9b29v7yJPI7fCtS/i5jNfwGLLknwRJ+6xJK/A4h4KWExTwGKaAhbTFLCYpoDFNAUspilgMU0Bi2kKWExTwGKaAhbTFLCYpoDFNAUspilgMU0Bi2kKWExTwGKaAhbTFLCYpoDFNAUspilgMU0Bi2kKWExTwGKaAhbTFLCYpoDFNAUspilgMU0Bi2kKWExTwGKaAhbTFLCYpoDFNAUspilgMU0Bi2kKWExTwGKaAhbTFLCYtiQCDgaDNDQ0UFBQQHJyMrm5udTX1xMKhdizZw8ej4fm5uZEjylRSEr0APHW2dlJTU0NgUCA1NRUioqKGBwc5PDhw/T09DA8PAxAWVlZYgeV6Dgu9v777zs5OTkO4Ozbt8+5evXq9FpTU5MDOElJSY7H43GuXLmSwEklWq4O+KmnnnIAp66uLuJ6aWmpAzg+n2+RJ5NYce09cHd3N62trWRnZ9PY2Bhxz5YtWwAoLS2dfqy9vZ3q6mrWrFnDHXfcQU5ODk888QTd3d2LMrcsjGvvgVtaWgiHw9TW1pKWlhZxz4oVK4CZAY+MjFBSUsLevXu566678Pv9NDY2UllZyR/+8AdycnIWZX65Oa4NuK2tDYCqqqo59/j9fmBmwDt37mTnzp0z9t13331s2LCBV199lfr6+jhMK9FybcB9fX0A5OXlRVyfmJjg1KlTwMyAI8nKygIgKSm6L1d5eTmBQCCqs0uF1+ulo6NjwedcG3AoFAJgfHw84nprayvBYJD09HR8Pt+s9cnJScLhMH19fXzjG9/A6/Xy+OOPRzVLIBBgYGAgqrMyP9cG7PV6GRkZ4cyZM1RWVs5YGxoaYv/+/QBs2rQJj8cz6/xDDz00fYUuKCigra2N1atXRz2LzC/qr1Gi3waJl6985SsO4OTm5joXLlyYfvy3v/2ts2HDBue2225zAOe5556LeP6dd95x3nzzTaelpcX55Cc/6eTk5Dh9fX2LNb7cJNcG3N/f72RlZU1/WHHvvfc6BQUFDuDU1NQ4n/rUpxzAOXbs2A2fa2RkxLnzzjvnjF0Sx7XvA+fk5NDe3s6OHTtITk6mt7eXzMxMjh49ysmTJ7l48SJw4xdwACtXrqSgoIB333033mPLAnkcx3ESPcRiGxsbIyMjA4/Hw7Vr10hJSZl3/3vvvce6det45pln+P73v79IU8rNcO2LuPmcO3cOx3EoLCycFe/TTz9NQUEBZWVlrFy5kj/+8Y9897vfJSkpia997WsJmljmsiQD7urqAiLfPmzdupWf/OQnfO973+P69evk5uZSVVXF888/P+d7ypI4Cvhj6urqqKurW+yRJEqufRE3n/kCFluW5Is4cY8leQUW91DAYpoCFtMUsJimgMU0BSymKWAxTQGLaQpYTFPAYpoCFtMUsJimgMU0BSymKWAxTQGLaQpYTFPAYpoCFtMUsJimgMU0BSymKWAxTQGLaQpYTFPAYpoCFtMUsJimgMU0BSymKWAxTQGLaQpYTFPAYpoCFtMUsJimgMU0BSymKWAxTQGLaQpYTFPAYpoCFtMUsJimgMU0BSymuT7gYDBIQ0MDBQUFJCcnk5ubS319PaFQiD179uDxeGhubk70mBKlpEQPEE+dnZ3U1NQQCARITU2lqKiIwcFBDh8+TE9PD8PDwwCUlZUldlCJnuNS77//vpOTk+MAzr59+5yrV69OrzU1NTmAk5SU5Hg8HufKlSsJnFRuhWsDfuqppxzAqauri7heWlrqAI7P51vkySSWXHkP3N3dTWtrK9nZ2TQ2Nkbcs2XLFgBKS0vnfJ6amho8Hg/f+ta34jGmxIArA25paSEcDlNbW0taWlrEPStWrADmDvinP/0pnZ2d8RpRYsSVL+La2toAqKqqmnOP3+8HIgd89epVvvrVr3Lo0CGefvrpW56nvLycQCBwy8/jZl6vl46OjgWfc2XAfX19AOTl5UVcn5iY4NSpU0DkgF944QUKCwupra2NScCBQICBgYFbfh6ZzZUBh0IhAMbHxyOut7a2EgwGSU9Px+fzzVjr6Ojg5Zdf5u23347ZPF6vN2bP5VbRfo1cGbDX62VkZIQzZ85QWVk5Y21oaIj9+/cDsGnTJjwez/Ta5OQke/fupa6ujuLi4pjNE823Rrk5rnwRV11dDUBTUxMXL16cfvz06dNUVVURDAaB2R9gNDc386c//UnvOhjiyoAbGhrIysqiv7+f4uJiSkpKWL9+PRUVFeTn57Nt2zZg5v1vMBjkxRdf5Jvf/CYTExOMjo4yOjoKwPXr1xkdHSUcDifijyPzSfQb0fFy/vx5Z8eOHU5aWpqTlpbmVFRUOEePHnXC4bDj8/kcwHnrrbem9//ud79zgHl/Xb58OXF/IInI4ziOk7B/PQkwNjZGRkYGHo+Ha9eukZKSMv14pHvVqqoqnn32Wb74xS+ydetWkpOTF3tkmYcrX8TN59y5cziOQ2Fh4XS8AGlpaTz88MMRz9xzzz1zrkliufIeeD5dXV3A/B8hix1L7gq80ICX2B2WOboCi2lL7kWcuMuSuwKLuyhgMU0Bi2kKWExTwGKaAhbTFLCYpoDFNAUspilgMU0Bi2kKWExTwGKaAhbTFLCYpoDFNAUspilgMU0Bi2kKWExTwGKaAhbTFLCYpoDFNAUspilgMU0Bi2kKWExTwGKaAhbTFLCYpoDFNAUspilgMU0Bi2kKWExTwGLa/wc8vQAf2axt2QAAAABJRU5ErkJggg==",
      "text/plain": [
       "<Figure size 203.885x451.5 with 1 Axes>"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "oracle = QuantumCircuit(5)\n",
    "oracle.ccz(0, 1, 2)\n",
    "oracle.draw(output='mpl')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Then, per default, the Grover operator implements the zero reflection on all five qubits."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {
    "tags": [
     "nbsphinx-thumbnail"
    ]
   },
   "outputs": [
    {
     "data": {
      "image/png": "iVBORw0KGgoAAAANSUhEUgAAA18AAAF7CAYAAAAt5DFgAAAAOXRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjYuMiwgaHR0cHM6Ly9tYXRwbG90bGliLm9yZy8o6BhiAAAACXBIWXMAAA9hAAAPYQGoP6dpAABiYUlEQVR4nO3de3xU1b3//9dccoEghIshJhACSYAQQKOAKNTbAQ8iArYoWqjiUbRKC4pKvP7EishNqV/ar3L5UrBF2koockQ9VcLF2gMSEUITAwRBSLhFgQgEcpnZvz9ipsREMpNMZk/2vJ+PRx6E2Xuv+Uz2Wnvtz6y917YZhmEgIiIiIiIiTcpudgAiIiIiIiKhQMmXiIiIiIhIACj5EhERERERCQAlXyIiIiIiIgGg5EtERERERCQAlHyJiIiIiIgEgJIvERERERGRAFDyJSIiIiIiEgBKvkRERERERAJAyZeIiIiIiEgANFnydcMNN/Doo482+TbBWoaIiIiIiMiFGpR8HT16lClTppCcnExkZCQdO3Zk0KBBvPHGG5SWlvo7Rr+aMGECNpsNm81GeHg4ycnJ/OY3v6GystLs0ERERERExMKcvm7w1VdfMWjQIKKjo5k5cyZ9+vQhIiKCXbt2sWjRIuLj4xk5cmRTxOo3w4YN4w9/+ANlZWW8//77TJo0ibCwMJ5++mmzQxMREREREYvyeeTrkUcewel0kp2dzZ133klqairdunVj1KhRrFu3jttuu63O7crKypg8eTIxMTFERkYyePBgtm3bVmu9yspKfvWrX9GmTRs6dOjA888/j2EYAHz44YcMHjyY6Oho2rdvz4gRI9i3b5+vH4GIiAhiY2Pp0qULDz/8MEOGDGHt2rU11nG73UybNo127doRGxvL9OnTPcu8iWPVqlX06dOHFi1a0L59e4YMGcLZs2c9Zb/yyit07dqVFi1acPnll7Nq1SqfP0dqaqpnFO+HP7/73e98Lk9ERERERJqOT8nXt99+y9///ncmTZpEVFRUnevYbLY6X582bRqZmZksX76c7du3k5yczH/+539y4sSJGustX74cp9PJZ599xuuvv85rr73GkiVLADh79ixTp04lOzub9evXY7fbuf3223G73b58jFpatGhBeXl5rTiioqLYunUrc+bM4Te/+Q0fffSRV3EcOXKEu+++m//6r//iyy+/ZOPGjfz0pz/1JJGvvPIKb731Fm+++Sa5ubk89thjjB8/nk2bNnnef9myZT/6t6yWmZkJwPr16zly5AgHDhzAbrfzzjvvMHHixEb9TURERERExM8MH2zZssUAjNWrV9d4vX379kZUVJQRFRVlTJs2zTAMw7j++uuNKVOmGIZhGGfOnDHCwsKMFStWeLYpLy834uLijDlz5nheu/76643U1FTD7XZ7XsvIyDBSU1PrjKe4uNgAjF27dtUoo/p963Lvvfcao0aNMgzDMNxut/HRRx8ZERERxhNPPFGjjMGDB9fYrn///kZGRoZXcXz++ecGYBw4cKDWuufPnzdatmxp/POf/6zx+v3332/cfffdnv+vXr3a6NGjx49+DsMwjKysLMPpdBrnz583DMMwsrOzDcA4evToRbcTEREREZHA88tsh5999hk7duwgLS2NsrKyWsv37dtHRUUFgwYN8rwWFhbGgAED+PLLL2usO3DgwBojPtdccw179+7F5XKxd+9e7r77brp160br1q1JTEwE4ODBgz7F+95779GqVSsiIyO55ZZbGDt2bI3LCgH69u1b4/+XXXYZx48fB6g3jssvv5z/+I//oE+fPtxxxx0sXryYkydPAlBQUEBpaSlDhw6lVatWnp+33nqrxqWLt99+O/n5+Rf9HLt27aJ79+5EREQAsHPnTmJiYujYsaNPfw8REREREWl6Pk24kZycjM1mY/fu3TVe79atG1B1+V5Tuu222+jSpQuLFy8mLi4Ot9tN7969a10yWJ8bb7yRN954g/DwcOLi4nA6a/8ZwsLCavzfZrN5LiusLw6Hw8FHH33EP//5T/7+97+zYMECnn32WbZu3cqZM2cAWLduHfHx8TXeozqJ8lZOTg59+vTx/H/nzp01/i8iIiIiIsHDp5Gv9u3bM3ToUH73u995Jo/wRlJSEuHh4Xz66aee1yoqKti2bRu9evWqse7WrVtr/H/Lli2kpKRw6tQpdu/ezXPPPcd//Md/kJqa6hlN8lVUVBTJyckkJCTUmXhdzLfffutVHDabjUGDBvHiiy/yxRdfEB4ezt/+9jd69epFREQEBw8eJDk5ucZP586dfYolJyenxgjdzp07a43YiYiIiIhIcPD5ssP/+3//L5WVlfTr14+//OUvfPnll+zevZs//elP5Ofn43A4am0TFRXFww8/zJNPPsmHH35IXl4eEydOpLS0lPvvv7/GugcPHmTq1Kns3r2blStXsmDBAqZMmULbtm1p3749ixYtoqCggKysLKZOndrwT95A3sSxdetWZs6cSXZ2NgcPHmT16tUUFxeTmprKJZdcwhNPPMFjjz3G8uXL2bdvH9u3b2fBggUsX77cU8bf/vY3evbs+aNxuN1ucnNzayRb+/bt81wCKSIiIiIiwcXn53wlJSXxxRdfMHPmTJ5++mkKCwuJiIigV69ePPHEEzzyyCN1bjdr1izcbje/+MUvOH36NP369eN//ud/aNu2bY317rnnHs6dO8eAAQNwOBxMmTKFBx98EJvNxp///GcmT55M79696dGjB//n//wfbrjhhgZ98Iay2+31xtG6dWs2b97Mb3/7W7777ju6dOnCq6++yi233ALASy+9xKWXXsorr7zCV199RXR0NFdeeSXPPPOMp4ySkpJal3deaN++fZSWltZIvvr06cMLL7zAVVddVeP+OhERERERMZ/NML6f/1xERERERESajF9mOxQREREREZGLU/IlIiIiIiISAEq+REREREREAkDJl4iIiIiISAAo+RIREREREQkAJV8iIiIiIiIBoORLREREREQkAJR8iYiIiIiIBICSLxERERERkQBQ8iUiIiIiIhIASr5EREREREQCQMmXiIiIiIhIACj5EhERERERCQAlXyIiIiIiIgGg5EtERERERCQAlHyJiIiIiIgEgJIvERERERGRAFDyJSIiIiIiEgBOswMQCRX5+fler3v8+HH++te/cueddxITE+P1dj179mxIaBIAvux/aFgd0P4XEQluOhcQjXyJBKHi4mJ+//vfU1xcbHYoYhLVARGR0KZ+wJqUfImIiIiIiASAki8REREREZEAUPIlIiIiIiISAEq+RIJQmzZtuO2222jTpo3ZoYhJVAdEREKb+gFrshmGYZgdhEgo8HW2u4bQDEfBS/tfRETUF4hGvkSCUFlZGV9//TVlZWVmhyImUR0QEQlt6gesScmXSBAqKChg2LBhFBQUmB2KmER1QEQktKkfsCY9ZFlEGsUwoNxldhTeC3eAzWZ2FNZhGAal7mZUAYCWdgc2VQLxo+bWDtQGxN90LuA9JV8i0ijlLsj4i9lReG/2WIjQkc9vSt0u2mZ9ZHYYPjl501CiHKoE4j/NrR2oDYi/6VzAe7rsUERERERE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",
      "text/plain": [
       "<Figure size 1094.88x451.5 with 1 Axes>"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from qiskit.circuit.library import GroverOperator\n",
    "grover_op = GroverOperator(oracle, insert_barriers=True)\n",
    "grover_op.decompose().draw(output='mpl')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "But we know that we only need to consider the first three:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "iVBORw0KGgoAAAANSUhEUgAAA18AAAF7CAYAAAAt5DFgAAAAOXRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjYuMiwgaHR0cHM6Ly9tYXRwbG90bGliLm9yZy8o6BhiAAAACXBIWXMAAA9hAAAPYQGoP6dpAABZJ0lEQVR4nO3de3wU5d338e9mNwcIh3AwiYRDgARIAmgsIApVa8GiRsAWRYUqVtEq3qBWiXh4xIrISS0P9bEcbgq2SFsJRW5RWySglt4i4RRMCBAEQ8LBaEiEBHLYneePmC0xkeyGZGcz+3m/XnkFdmau/W3mN3vNb6/Za2yGYRgCAAAAADSrILMDAAAAAIBAQPEFAAAAAD5A8QUAAAAAPkDxBQAAAAA+QPEFAAAAAD5A8QUAAAAAPkDxBQAAAAA+QPEFAAAAAD5A8QUAAAAAPkDxBQAAAAA+0GzF13XXXadHH3202bfx1zYAAAAA4HyNKr5OnDihadOmKS4uTmFhYYqKitKwYcP0xhtvqKysrKljbFKTJk2SzWaTzWZTSEiI4uLi9Nvf/lZVVVVmhwYAAADAwhzebvDFF19o2LBhioiI0OzZszVgwACFhoZq7969WrJkiWJiYjR69OjmiLXJjBo1Sn/84x9VXl6u9957T1OmTFFwcLBmzJhhdmgAAAAALMrrka+HH35YDodDGRkZuv3225WQkKBevXppzJgx2rBhg2655ZZ6tysvL9fUqVMVGRmpsLAwDR8+XNu3b6+zXlVVlR555BG1b99enTt31nPPPSfDMCRJH3zwgYYPH66IiAh16tRJKSkpOnTokLcvQaGhoYqOjlaPHj300EMPacSIEVq/fn2tdVwul6ZPn66OHTsqOjpaM2fOdC/zJI41a9ZowIABatWqlTp16qQRI0aotLTU3fbLL7+snj17qlWrVrrsssu0Zs0ar19HQkKCexTv+z+///3vvW4PAAAAQPPxqvj65ptv9M9//lNTpkxReHh4vevYbLZ6H58+fbrS0tK0cuVK7dy5U3FxcfrZz36moqKiWuutXLlSDodDn332mRYuXKhXX31Vy5YtkySVlpbq8ccfV0ZGhjZt2qSgoCDdeuutcrlc3ryMOlq1aqWKioo6cYSHh2vbtm2aN2+efvvb32rjxo0exXH8+HHdeeed+tWvfqV9+/Zpy5Yt+vnPf+4uIl9++WW9+eab+sMf/qCsrCw99thjmjhxoj766CP3869YseIH/5Y10tLSJEmbNm3S8ePHdeTIEQUFBentt9/W5MmTL+pvAgAAAKCJGV749NNPDUnG2rVraz3eqVMnIzw83AgPDzemT59uGIZhXHvttca0adMMwzCMM2fOGMHBwcaqVavc21RUVBhdunQx5s2b537s2muvNRISEgyXy+V+LDU11UhISKg3nsLCQkOSsXfv3lpt1Dxvfe655x5jzJgxhmEYhsvlMjZu3GiEhoYaTzzxRK02hg8fXmu7wYMHG6mpqR7FsWPHDkOSceTIkTrrnjt3zmjdurXx73//u9bj9913n3HnnXe6/7927Vqjb9++P/g6DMMw0tPTDYfDYZw7d84wDMPIyMgwJBknTpy44HYAAAAAfK9JZjv87LPPtHv3biUlJam8vLzO8kOHDqmyslLDhg1zPxYcHKwhQ4Zo3759tdYdOnRorRGfq666SgcPHpTT6dTBgwd15513qlevXmrXrp1iY2MlSXl5eV7F++6776pNmzYKCwvTjTfeqPHjx9e6rFCSBg4cWOv/l156qb766itJajCOyy67TD/96U81YMAA3XbbbVq6dKlOnTolScrNzVVZWZlGjhypNm3auH/efPPNWpcu3nrrrcrJybng69i7d6/69Omj0NBQSdKePXsUGRmpqKgor/4eAAAAAJqfVxNuxMXFyWazaf/+/bUe79Wrl6Tqy/ea0y233KIePXpo6dKl6tKli1wul/r371/nksGG/OQnP9Ebb7yhkJAQdenSRQ5H3T9DcHBwrf/bbDb3ZYUNxWG327Vx40b9+9//1j//+U8tWrRIzzzzjLZt26YzZ85IkjZs2KCYmJhaz1FTRHkqMzNTAwYMcP9/z549tf4PAAAAwH94NfLVqVMnjRw5Ur///e/dk0d4onfv3goJCdHWrVvdj1VWVmr79u1KTEyste62bdtq/f/TTz9VfHy8iouLtX//fj377LP66U9/qoSEBPdokrfCw8MVFxen7t2711t4Xcg333zjURw2m03Dhg3TCy+8oF27dikkJER///vflZiYqNDQUOXl5SkuLq7WT7du3byKJTMzs9YI3Z49e+qM2AEAAADwD15fdvj//t//U1VVlQYNGqS//vWv2rdvn/bv368///nPysnJkd1ur7NNeHi4HnroIT355JP64IMP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",
      "text/plain": [
       "<Figure size 1094.88x451.5 with 1 Axes>"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "grover_op = GroverOperator(oracle, reflection_qubits=[0, 1, 2], insert_barriers=True)\n",
    "grover_op.decompose().draw(output='mpl')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Dive into other arguments of `Grover`\n",
    "`Grover` has arguments other than `oracle` and `state_preparation`. We will explain them in this section.\n",
    "\n",
    "### Specifying `good_state`\n",
    "`good_state` is used to check whether the measurement result is correct or not internally. It can be a list of binary strings, a list of integer, `Statevector`, and Callable. If the input is a list of bitstrings, each bitstrings in the list represents a good state. If the input is a list of integer, each integer represent the index of the good state to be $|1\\rangle$. If it is a `Statevector`, it represents a superposition of all good states.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {
    "tags": []
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "True\n"
     ]
    }
   ],
   "source": [
    "# a list of binary strings good state\n",
    "oracle = QuantumCircuit(2)\n",
    "oracle.cz(0, 1)\n",
    "good_state = ['11', '00']\n",
    "problem = AmplificationProblem(oracle, is_good_state=good_state)\n",
    "print(problem.is_good_state('11'))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "True\n"
     ]
    }
   ],
   "source": [
    "# a list of integer good state\n",
    "oracle = QuantumCircuit(2)\n",
    "oracle.cz(0, 1)\n",
    "good_state = [0, 1]\n",
    "problem = AmplificationProblem(oracle, is_good_state=good_state)\n",
    "print(problem.is_good_state('11'))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {
    "tags": []
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "True\n"
     ]
    }
   ],
   "source": [
    "from qiskit.quantum_info import Statevector\n",
    "\n",
    "# `Statevector` good state\n",
    "oracle = QuantumCircuit(2)\n",
    "oracle.cz(0, 1)\n",
    "good_state = Statevector.from_label('11')\n",
    "problem = AmplificationProblem(oracle, is_good_state=good_state)\n",
    "print(problem.is_good_state('11'))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {
    "tags": []
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "True\n"
     ]
    }
   ],
   "source": [
    "# Callable good state\n",
    "def callable_good_state(bitstr):\n",
    "    if bitstr == \"11\":\n",
    "        return True\n",
    "    return False\n",
    "\n",
    "oracle = QuantumCircuit(2)\n",
    "oracle.cz(0, 1)\n",
    "problem = AmplificationProblem(oracle, is_good_state=good_state)\n",
    "print(problem.is_good_state('11'))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### The number of `iterations`\n",
    "\n",
    "The number of repetition of applying the Grover operator is important to obtain the correct result with Grover's algorithm. The number of iteration can be set by the `iteration` argument of `Grover`. The following inputs are supported:\n",
    "* an integer to specify a single power of the Grover operator that's applied\n",
    "* or a list of integers, in which all these different powers of the Grover operator are run consecutively and after each time we check if a correct solution has been found\n",
    "\n",
    "Additionally there is the `sample_from_iterations` argument. When it is `True`, instead of the specific power in `iterations`, a random integer between 0 and the value in `iteration` is used as the power Grover's operator. This approach is useful when we don't even know the number of solution.\n",
    "\n",
    "For more details of the algorithm using `sample_from_iterations`, see [4].\n",
    "\n",
    "**References:**\n",
    "\n",
    "[4]: Boyer et al., Tight bounds on quantum searching [arxiv:quant-ph/9605034](https://arxiv.org/abs/quant-ph/9605034)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [],
   "source": [
    "# integer iteration\n",
    "oracle = QuantumCircuit(2)\n",
    "oracle.cz(0, 1)\n",
    "problem = AmplificationProblem(oracle, is_good_state=['11'])\n",
    "grover = Grover(iterations=1)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [],
   "source": [
    "# list iteration\n",
    "oracle = QuantumCircuit(2)\n",
    "oracle.cz(0, 1)\n",
    "problem = AmplificationProblem(oracle, is_good_state=['11'])\n",
    "grover = Grover(iterations=[1, 2, 3])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [],
   "source": [
    "# using sample_from_iterations\n",
    "oracle = QuantumCircuit(2)\n",
    "oracle.cz(0, 1)\n",
    "problem = AmplificationProblem(oracle, is_good_state=['11'])\n",
    "grover = Grover(iterations=[1, 2, 3], sample_from_iterations=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When the number of solutions is known, we can also use a static method `optimal_num_iterations` to find the optimal number of iterations. Note that the output iterations is an approximate value. When the number of qubits is small, the output iterations may not be optimal. In addition, the calculation of this value assumes the standard uniform superposition state preparation and may not be accurate for other state preparations.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "12"
      ]
     },
     "execution_count": 18,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "iterations = Grover.optimal_num_iterations(num_solutions=1, num_qubits=8)\n",
    "iterations"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Applying `post_processing`\n",
    "We can apply an optional post processing to the top measurement for ease of readability. It can be used e.g. to convert from the bit-representation of the measurement `[1, 0, 1]` to a DIMACS CNF format `[1, -2, 3]`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[1, -2, 3]"
      ]
     },
     "execution_count": 19,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "def to_DIAMACS_CNF_format(bit_rep):\n",
    "    return [index+1 if val==1 else -1 * (index + 1) for index, val in enumerate(bit_rep)]\n",
    "\n",
    "oracle = QuantumCircuit(2)\n",
    "oracle.cz(0, 1)\n",
    "problem = AmplificationProblem(oracle, is_good_state=['11'], post_processing=to_DIAMACS_CNF_format)\n",
    "problem.post_processing([1, 0, 1])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<h3>Version Information</h3><table><tr><th>Qiskit Software</th><th>Version</th></tr><tr><td><code>qiskit-terra</code></td><td>0.23.0.dev0+0f6c75e</td></tr><tr><td><code>qiskit-aer</code></td><td>0.11.1</td></tr><tr><td><code>qiskit-optimization</code></td><td>0.5.0</td></tr><tr><th>System information</th></tr><tr><td>Python version</td><td>3.9.10</td></tr><tr><td>Python compiler</td><td>Clang 13.1.6 (clang-1316.0.21.2.5)</td></tr><tr><td>Python build</td><td>main, Aug  9 2022 18:26:17</td></tr><tr><td>OS</td><td>Darwin</td></tr><tr><td>CPUs</td><td>10</td></tr><tr><td>Memory (Gb)</td><td>64.0</td></tr><tr><td colspan='2'>Fri Nov 25 21:25:09 2022 JST</td></tr></table>"
      ],
      "text/plain": [
       "<IPython.core.display.HTML object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "text/html": [
       "<div style='width: 100%; background-color:#d5d9e0;padding-left: 10px; padding-bottom: 10px; padding-right: 10px; padding-top: 5px'><h3>This code is a part of Qiskit</h3><p>&copy; Copyright IBM 2017, 2022.</p><p>This code is licensed under the Apache License, Version 2.0. You may<br>obtain a copy of this license in the LICENSE.txt file in the root directory<br> of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.<p>Any modifications or derivative works of this code must retain this<br>copyright notice, and modified files need to carry a notice indicating<br>that they have been altered from the originals.</p></div>"
      ],
      "text/plain": [
       "<IPython.core.display.HTML object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "import qiskit.tools.jupyter\n",
    "%qiskit_version_table\n",
    "%qiskit_copyright"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.9.10"
  },
  "vscode": {
   "interpreter": {
    "hash": "4213929014e7aa4f7c83ab6e8b511ecef456337e6cdcd5a9f1a6614ced2a54b2"
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}
